electron-builder 配置详解
概述
本节深入讲解 electron-builder 的配置方法，并介绍学习新技术配置文件的通用方法论：如何从官方文档、知名开源项目（Awesome Electron、Electron 官方应用列表）中快速掌握配置技巧。
学习配置的方法论
学习新工具配置的推荐路径
1. 阅读官方文档（最权威）
↓ 如果英文有困难
2. 查找活跃的开源项目作为参考
↓ 找到 electron-builder 的标志性依赖
3. 分析其 package.json 和构建配置
↓ 对比自己项目做调整
4. 验证构建结果
text
参考资源
| 资源 | 说明 | 使用方式 |
|---|---|---|
| electron-builder 官方文档 | 最权威的配置参考 | 按目录查找具体配置项 |
| Awesome Electron | Electron 优秀项目合集 | 找同类项目的构建配置 |
| Electron 官方应用列表 | 按分类筛选高质量应用 | 查看 GitHub 仓库的构建脚本 |
package.json 搜索 | 在目标项目中搜索 electron-builder | 确认是否使用 electron-builder |
注意：不建议直接从搜索引擎复制配置，因为版本差异可能导致配置失效。优先参考活跃维护的项目。
完整配置详解
配置文件格式选择
| 格式 | 文件 | 优势 | 适用场景 |
|---|---|---|---|
| TypeScript | electron-builder.config.ts | 类型提示、IDE 补全 | 推荐所有项目 |
| JavaScript | electron-builder.config.js | 灵活动态配置 | 需要条件判断 |
| YAML | electron-builder.yml | 简洁易读 | 简单配置 |
| JSON | package.json 的 build 字段 | 集中管理 | 小项目 |
完整配置示例
// electron-builder.config.ts
import type { Configuration } from 'electron-builder'
const config: Configuration = {
// ========== 基础配置 ==========
appId: 'com.toimc.tools',
productName: 'toimc-tools',
copyright: 'Copyright © 2026 toimc',
directories: {
output: 'dist',
buildResources: 'build'
},
// ========== 文件处理 ==========
files: [
'dist-electron/**/*',
'dist/**/*',
'!node_modules/**/{test,tests,__tests__,spec}/**',
'!node_modules/**/*.md',
'!node_modules/**/*.ts',
'!{.git,.github,.vscode,docs}/**/*'
],
// ========== ASAR 归档 ==========
asar: true,
asarUnpack: [
'**/*.node', // 原生模块
'node_modules/sharp/**', // 特定原生依赖
'plugins/**' // 动态加载的插件
],
// ========== 额外资源 ==========
extraResources: [
{
from: 'plugins',
to: 'plugins',
filter: ['**/*.js', '**/*.json']
}
],
// ========== 压缩与优化 ==========
compression: 'maximum', // 'store' | 'normal' | 'maximum'
removePackageScripts: true,
removePackageKeywords: true,
// ========== macOS 配置 ==========
mac: {
category: 'public.app-category.developer-tools',
target: [
{ target: 'dmg', arch: ['arm64', 'x64'] },
{ target: 'zip', arch: ['arm64', 'x64'] }
],
icon: 'build/icon.icns',
hardenedRuntime: true,
gatekeeperAssess: false,
darkModeSupport: true,
extendInfo: {
NSDocumentsFolderUsageDescription: '需要访问文档目录',
NSDownloadsFolderUsageDescription: '需要访问下载目录'
}
},
// ========== DMG 安装镜像 ==========
dmg: {
title: '${productName} ${version}',
window: { x: 100, y: 100, width: 540, height: 380 },
contents: [
{ x: 130, y: 220 },
{ x: 410, y: 220, type: 'link', path: '/Applications' }
]
},
// ========== Windows 配置 ==========
win: {
target: [
{ target: 'nsis', arch: ['x64', 'arm64'] },
{ target: 'portable', arch: ['x64'] }
],
icon: 'build/icon.ico',
requestedExecutionLevel: 'asInvoker',
verifyUpdateCodeSignature: true
},
// ========== NSIS 安装程序 ==========
nsis: {
oneClick: false,
perMachine: false,
allowToChangeInstallationDirectory: true,
createDesktopShortcut: true,
createStartMenuShortcut: true,
shortcutName: 'toimc-tools',
uninstallDisplayName: 'toimc-tools',
installerLanguages: ['zh_CN', 'en_US'],
language: '2052' // 简体中文
},
// ========== Linux 配置 ==========
linux: {
target: ['AppImage', 'deb'],
icon: 'build/icon.png',
category: 'Development',
desktop: {
Name: 'toimc-tools',
Comment: 'A developer tools built with Electron',
StartupWMClass: 'toimc-tools'
}
},
// ========== 发布配置 ==========
publish: {
provider: 'github',
owner: 'toimc',
repo: 'toimc-tools',
releaseType: 'release'
}
}
export default config
typescript
核心配置项分类解析
文件与目录
| 配置项 | 默认值 | 说明 |
|---|---|---|
files | ['**/*'] | 包含文件模式（支持排除 !） |
extraResources | [] | 额外资源（不打包进 asar） |
extraFiles | [] | 额外文件 |
asar | true | 启用 asar 归档 |
asarUnpack | [] | asar 中不解包的文件模式 |
directories.output | dist | 构建输出目录 |
directories.buildResources | build | 构建资源目录 |
构建优化
| 配置项 | 可选值 | 影响 |
|---|---|---|
compression | store / normal / maximum | 安装包大小 vs 构建速度 |
removePackageScripts | boolean | 移除 package.json 中的 scripts |
nodeGypRebuild | boolean | 是否重建原生模块 |
macOS 签名与公证
mac: {
identity: 'Developer ID Application: Your Name (TEAM_ID)',
entitlements: 'build/entitlements.mac.plist',
entitlementsInherit: 'build/entitlements.mac.inherit.plist',
hardenedRuntime: true, // 公证必需
gatekeeperAssess: false // 跳过 Gatekeeper 评估
}
typescript
Windows 代码签名
win: {
signtoolOptions: {
certificateFile: process.env.WIN_CERT_FILE,
certificatePassword: process.env.WIN_CERT_PASSWORD,
signingHashAlgorithms: ['sha256']
}
}
typescript
自动更新配置
publish: {
provider: 'github',
owner: 'your-org',
repo: 'your-repo'
}
typescript
// 主进程中检查更新
import { autoUpdater } from 'electron-updater'
autoUpdater.checkForUpdatesAndNotify()
typescript
构建命令速查
# 构建当前平台
npx electron-builder
# 指定平台
npx electron-builder --mac
npx electron-builder --win --x64
npx electron-builder --linux --arm64
# 仅打包目录（不生成安装包，用于调试）
npx electron-builder --dir
# 指定配置文件
npx electron-builder --config custom.config.ts
# 发布
npx electron-builder --publish always
bash
实践要点
- 学习新工具配置的标准路径：官方文档 → 活跃开源项目 → 对比调整 → 验证构建
- 通过在 GitHub 仓库中搜索
electron-builder依赖，确认目标项目是否使用该工具 - 优先参考更新频率高、star 数多的项目配置，避免使用过时的配置方式
asarUnpack用于处理原生模块（.node文件），这些模块必须从 asar 中解包才能加载- macOS 公证需要
hardenedRuntime: true和有效的开发者证书 - Windows 签名证书应通过环境变量传递，避免在代码中硬编码
↑